import CodeView from '../../../shared/components/CodeView';
import CodeBlock from '../../../shared/components/CodeBlock';
import Blockquote from '../../../shared/components/Blockquote';
import StylingHooksTable from '../../../shared/components/StylingHooksTable';
import { getDisplayElementById } from '../../shared/helpers';
import { MobileNotice, MobileBlurb } from '../../shared/doc-text';
import * as PillsExamplesBase from './base/example';
import * as PillsExamplesListbox from './listbox-of-pill-options/example';

<div className="lead doc">
  A pill represents an object that can be viewed with or without an icon.
</div>

<CodeView exampleOnly>
  {getDisplayElementById(PillsExamplesBase.examples, 'icon')}
</CodeView>

## About Pills

To create a pill, apply the `.slds-pill` class on a `<span>`.

Depending on your context, you will either need a base pill (linked or unlinked), or a pill option inside of a listbox. Note that a linked pill should not be used as a pill option inside of a listbox.

For linked pills, a modifier class of `slds-pill_link` needs to be added to the existing `<span>` with the class name of `slds-pill`. You need an `<a>` inside of the span with the `slds-pill_link` class. The `<a>` will get the class name of `slds-pill__action`. This will treat the interactions differently from an unlinked pill option inside of a listbox.

For both linked and unlinked pills, a `<span>` with the class name of `slds-pill__label` should contain the string of text describing the pill object.

Additionally, a pill can have an icon or image that sits to the left-hand side of the `.slds-pill__label`. That icon or image should receive the class `.slds-pill__icon_container`.

You may also want the functionality to remove the pill as a selection. An "X" icon is normally used and will sit to the right-hand side of the `.slds-pill__label`. That icon should receive the class `.slds-pill__remove`.

A `.slds-pill_container` can be used as a visual container for multiple pill(s).

### Mobile

<MobileBlurb patternSpecificText="pills will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor" />

<CodeView frameOnly frameTitle="Example mobile styles for pills">
  {getDisplayElementById(PillsExamplesBase.examples, 'icon')}
</CodeView>

## Base

<CodeView>{getDisplayElementById(PillsExamplesBase.default)}</CodeView>

### Examples

#### With Icon

<CodeView>{getDisplayElementById(PillsExamplesBase.examples, 'icon')}</CodeView>

#### With Avatar

<CodeView>
  {getDisplayElementById(PillsExamplesBase.examples, 'avatar')}
</CodeView>

#### Pill with Container

<CodeView>
  {getDisplayElementById(PillsExamplesBase.examples, 'container')}
</CodeView>

### States

#### Error

<CodeView>{getDisplayElementById(PillsExamplesBase.states, 'error')}</CodeView>

#### Truncated

The pills component will respect the width of its parent and truncate if necessary.

<CodeView demoStyles="width: 220px;">
  {getDisplayElementById(PillsExamplesBase.states, 'truncated')}
</CodeView>

Showing the full text of a truncated pill as a tooltip.

<CodeView demoStyles="width: 220px; padding-top:48px;">
  {getDisplayElementById(PillsExamplesBase.states, 'pill-truncated-tooltip')}
</CodeView>

## Listbox Of Pill Options

<CodeView>{getDisplayElementById(PillsExamplesListbox.default)}</CodeView>

A Listbox of Pills is a way to display a list of selected options when performing user input, usually from a multi-select [Combobox](/components/combobox), [Lookup](/components/lookups) or [Picklist](/components/picklist).

Note that we can use a linked or unlinked pill as a pill item inside of a listbox

### Accessibility

**Interaction requirements**

- Only 1 focused Pill per set of Pills
- The remove button is a focusable element and can be clickable.

**Keyboard navigation**

- The first `pill` in the list will be take user focus initially, when tabbed to
- `Right` arrow key will move focus to the next pill in the list
- `Left` arrow key will move focus to the previous pill in the list
- `Left` arrow key when on the first `pill` should cycle user focus to the last `pill`
- `Right` arrow key when on the last `pill` should cycle user focus to the first `pill`
- On removing of the pill, the focus should then be placed on the nearest `pill`
  - When on the last `pill`, place user focus on the previous `pill`
  - When on the first `pill`, place user focus on the next `pill`
  - When on the only `pill`, place user focus on the `listbox` or any `input` element the `pill` might be associated with

### Examples

#### With Icon

<CodeView>
  {getDisplayElementById(
    PillsExamplesListbox.examples,
    'listbox-pill-with-icon'
  )}
</CodeView>

#### With Avatar

<CodeView>
  {getDisplayElementById(
    PillsExamplesListbox.examples,
    'listbox-pill-with-avatar'
  )}
</CodeView>

### Layout

#### Bare

<CodeView>
  {getDisplayElementById(PillsExamplesListbox.examples, 'listbox-pill-bare')}
</CodeView>

## Styling Hooks Overview

<StylingHooksTable name="pills" type="component" />
